home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 3 / MacMania 3.toast / Tools&Utilities / extensions 12 strip / Developer’s toolkit / Headers / ExtensionsStrip.p.THINK < prev    next >
Encoding:
Text File  |  1995-12-09  |  14.7 KB  |  346 lines  |  [TEXT/PJMM]
  1. {}
  2. {     File:        ExtensionsStrip.p for THINK (LightSpeed) Pascal}
  3. { }
  4. {     Contains:    Extensions Strip Specific Interfaces for Control Strip modules.}
  5. { }
  6. {     Version:    Technology:    System 7.1+ (System 7.5+ preferred)}
  7. {                 Package:    Extensions Strip 1.2}
  8. { }
  9. {     Copyright:    © 1995 by Ammon Skidmore, Skidperfect Software Inc.}
  10. {                 All rights reserved.}
  11. { }
  12. {     Bugs?:        If you find a problem, have a criticism or comment with this}
  13. {                 file, please inform the author at the following address:}
  14. {                     Internet:    skidperfect@kagi.com}
  15. {}
  16.  
  17. unit ExtensionsStrip;
  18. interface
  19.  
  20.     uses
  21.         ControlStrip;
  22.  
  23. {******************************************************************************************}
  24. {}
  25. {    Special Extensions Strip selector calls to modules.}
  26. {}
  27. {******************************************************************************************}
  28.     const
  29.         sdevInAppContext = 2000;        {   called only once after the module specifically        }
  30.                                         {   requested to be executed from inside Extension        }
  31.                                         {   Strip's context. NB: you can return the special        }
  32.                                         {   result values.                                        }
  33.                                         {}
  34.         sdevInterceptedEvent = 2001;    {    if the module returned the sdevInterceptAllEvents    }
  35.                                         {   flag in its features, then this selector            }
  36.                                         {   will get called before _each_ event is processed    }
  37.                                         {   by Extensions Strip.  Meant to be used with            }
  38.                                         {   _SBGetCurrentEvent so each event can be looked at,    }
  39.                                         {   and modified if necessary (to prevent passing.)        }
  40.                                         {   NB: you can return the special result values.        }
  41.                                         {}
  42.         sdevDragAccept = 2002;        {    return 0 if you accept the current drag, and        }
  43.                                         {   1 if you do not.  Modules that do not have any        }
  44.                                         {   drag handlers will never get this called.            }
  45.                                         {   NB: sdevDragAccept is only called from within        }
  46.                                         {   Extensions Strip's dragTrackingInWindow.  So it        }
  47.                                         {   is recommended to only check if you accept the drag    }
  48.                                         {   from within your dragTrackingEnterWindow, and then    }
  49.                                         {   set a global var that you can pass onto ES.            }
  50.                                         {}
  51.         sdevEventMask = 2003;            {    if the module returned the sdevInterceptAllEvents    }
  52.                                         {   flag in its features, this selector will get        }
  53.                                         {   called to find the event mask to use.  Return your    }
  54.                                         {   mask as the result value of the sdev call.            }
  55.                                         {   sdevEventMask is called once upon initialization,    }
  56.                                         {   and every time sdevFeaturesChange is requested.        }
  57.  
  58.  
  59. {******************************************************************************************}
  60. {}
  61. {    Features supported by the module.  If a bit is set, it means that feature is supported.}
  62. {}
  63. {    Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module}
  64. {    will receive clicks and Extensions Strip (plus Desktop Strip) will not}
  65. {    auto-hilite your module.}
  66. {}
  67. {******************************************************************************************}
  68.         sdevHasDragHandlers = 31;        {    module has installed a drag tracking and/or            }
  69.                                         {   receive handler in the Strip window.                }
  70.                                         {}
  71.         sdevDontPeriodicTickle = 30;    {    module does not require any idle time so            }
  72.                                         {   by setting this bit it will never get                }
  73.                                         {   called with the sdevPeriodicTickle                     }
  74.                                         {   selector.  Note that you can set this along            }
  75.                                         {   with the sdevInterceptAllEvents bit (if you want)    }
  76.                                         {   and sdevInterceptedEvent will still get called.        }
  77.                                         {   So be nice and set this to help speed up idle        }
  78.                                         {   time processing.                                    }
  79.                                         {}
  80.         sdevInterceptAllEvents = 29;    {    module wants to be executed before each                }
  81.                                         {   event passes through Extension Strip's                }
  82.                                         {   jGNE filter.  Because the module is allowed            }
  83.                                         {   to modify every event, there is no more need        }
  84.                                         {   for modules, such as Terminator Strip, to            }
  85.                                         {   install their own jGNE filters!                        }
  86.                                         {   NB: You need to return an event mask when your        }
  87.                                         {   module is called by the sdevEventMask selector.        }
  88.  
  89.  
  90. {******************************************************************************************}
  91. {}
  92. {    Special result values returned by the sdevPeriodicTickle and sdevIconMouseClick selectors.}
  93. {    If a bit is set, the module can request that a specific function is performed by}
  94. {    the Control Strip.  All undefined bits should be set to zero.}
  95. {}
  96. {    Note: these values can also be returned by the sdevInAppContext and    }
  97. {    sdevInterceptedEvent selectors.                                            }
  98. {}
  99. {******************************************************************************************}
  100.         sdevQueueModule = 31;            {    module needs to be executed from within            }
  101.                                         {   Extension Strip's context: useful for                }
  102.                                         {   things like sending AppleEvents or                    }
  103.                                         {   creating and tracking new drags.                    }
  104.                                         {}
  105.         sdevFeaturesChange = 30;        {    module wants to change its feature flags. Useful    }
  106.                                         {   for changing clickable state of the module and        }
  107.                                         {   for locking/unlocking the sdev code.                    }
  108.  
  109. {******************************************************************************************}
  110. {}
  111. {    miscellaneous}
  112. {}
  113. {******************************************************************************************}
  114.         kModuleFolderType = 'sdev';            { FindFolder type for the root folder        }
  115.         kModuleDisabledFolderType = 'sdeD';    { FindFolder type for the disabled            }
  116.                                                 { root folder (place to put inactive        }
  117.                                                 { modules that you don't want deleted.)        }
  118.         sdevTypeCodePPC = 'Sdev';                { resource type for module's PPC code        }
  119.  
  120.         gestaltExtensionsStripAttr = 'CsEs';    {returns Extensions Strip's attributes.        }
  121.     { currently returned bits from gestaltExtensionsStripAttr: }
  122.         gestaltExtensionsStripExists = 0;        {Extensions Strip is currently launched        }
  123.         gestaltSupportsFontTraps = 1;            { The new font traps of Control Strip 1.2    }
  124.                                                 { are supported.  ES 1.0 incorrectly gave    }
  125.                                                 { Control Strip's font trap gestalt bit.    }
  126.         gestaltHasSBResolveAliasFile = 2;        { ES contains the new alias resolving trap.    }
  127.                                                 { This bit also signifies that ES can only    }
  128.                                                 { be run as a regular application.            }
  129.  
  130.         gestaltDesktopStripAttr = 'CsWT';        { returns the Desktop Strip program            }
  131.                                                 { attributes which are supported by            }
  132.                                                 { Extensions Strip.  See Desktop Strip's    }
  133.                                                 { docs for details about the bits            }
  134.  
  135.     type
  136.         ModuleReference = LONGINT;
  137.  
  138.  
  139.         SBQueueProcPtr = ProcPtr;  { PROCEDURE SBQueue(refCon: LONGINT); }
  140.         SBQueueUPP = ProcPtr;
  141.  
  142.     const
  143.         uppQueueProcProcInfo = $000000C0; { PROCEDURE (4 byte param); }
  144.  
  145.     function NewSBQueueProcProc (userRoutine: SBQueueProcPtr): SBQueueUPP;
  146.     inline
  147.         $2E9F;
  148.  
  149. {******************************************************************************************}
  150. {}
  151. {    Control Strip trap calls}
  152. {}
  153. {******************************************************************************************}
  154.  
  155. {                                                                                                }
  156. { All routines are documented as to whether the Extensions Strip implementation         }
  157. { of them they may move memory.  You can trust that a routine that says it            }
  158. { will not move memory in this version, will not move memory in future versions.    }
  159. { Note though, that some Universal Control Strip traps may move memory under        }
  160. { Control/Desktop Strip but not in Extensions Strip (such as                                }
  161. { _SBIsControlStripVisible and _SBShowHideControlStrip.)                                }
  162. {                                                                                                }
  163.  
  164. { =========================================== }
  165. { ========== Universal Control Strip traps ========== }
  166. { =========================================== }
  167. {}
  168. {'Yes' = May move memory!}
  169. {'No'  = Will not move memory.}
  170. {'unimplemented'    = Trap not supported by Extensions Strip when this header file}
  171. {                was released.  Check the Control Strip gestalt features to}
  172. {                determine if/when Extensions Strip supports these traps.}
  173. {}
  174. {SBIsControlStripVisible        no}
  175. {SBShowHideControlStrip        no}
  176. {SBSafeToAccessStartupDisk    no}
  177. {SBOpenModuleResourceFile    yes}
  178. {SBLoadPreferences            yes}
  179. {SBSavePreferences            yes}
  180. {SBGetDetachedIndString        no}
  181. {SBGetDetachIconSuite        yes}
  182. {SBTrackPopupMenu            yes}
  183. {SBTrackSlider                yes}
  184. {SBShowHelpString            yes}
  185. {SBGetBarGraphWidth            no}
  186. {SBDrawBarGraph                yes}
  187. {SBModalDialogInContext        yes}
  188. {}
  189. {Control Strip 1.2 and later}
  190. {---------------------------}
  191. {SBGetControlStripFontID        no}
  192. {SBSetControlStripFontID        no}
  193. {SBGetControlStripFontSize    no}
  194. {SBSetControlStripFontSize    no}
  195. {SBGetShowHideHotKey            unimplemented}
  196. {SBSetShowHideHotKey            unimplemented}
  197. {SBIsShowHideHotKeyEnabled    unimplemented}
  198. {SBEnableShowHideHotKey        unimplemented}
  199. {}
  200.  
  201. { ============================================ }
  202. { ========== Extensions Strip specific traps ========== }
  203. { ============================================ }
  204.  
  205. { Strip Window Utilities }
  206.  
  207.     { returns: true = vertical; false = horizontal }
  208.     {}
  209.         { Will not move memory. }
  210.     function SBIsControlStripVertical (stripPort: WindowPtr): BOOLEAN;
  211.     inline
  212.         $70FF, $AAF2;
  213.  
  214.     { returns pixel depth of the monitor this Strip window is in (always a power of 2) }
  215.     {}
  216.         { Will not move memory. }
  217.     function SBGetControlStripDepth (stripPort: WindowPtr): INTEGER;
  218.     inline
  219.         $70FE, $AAF2;
  220.  
  221.     { returns the current normal back color of this Strip window }
  222.     {}
  223.         { Will not move memory. }
  224.     procedure SBGetStripBackColor (var color: RGBColor; stripPort: WindowPtr);
  225.     inline
  226.         $70FD, $AAF2;
  227.  
  228.     { returns the current back color of this Strip window when a module is selected }
  229.     {}
  230.         { Will not move memory. }
  231.     procedure SBGetStripSelectedColor (var color: RGBColor; stripPort: WindowPtr);
  232.     inline
  233.         $70FC, $AAF2;
  234.  
  235. { Module Utilities }
  236.  
  237.     { returns a reference number that all of the Module Utilities need                }
  238.         { NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,        }
  239.         {   you should save its value into your globals if you are going to use        }
  240.         {   one of the Module Utilities later, such as inside a tracking handler.    }
  241.     { Also, the reference number will always be non-zero. }
  242.     {}
  243.         { Will not move memory. }
  244.     function SBGetMyReferenceNum: ModuleReference;
  245.     inline
  246.         $70FB, $AAF2;
  247.  
  248.     { total window space taken up by a module.  Useful for drag-n-drop calculations }
  249.     { note that this rect will always be larger than the module's statusRect. }
  250.     {}
  251.         { Will not move memory. }
  252.     procedure SBGetTotalModuleBounds (var bounds: Rect; stripPort: WindowPtr; moduleRefNum: ModuleReference);
  253.     inline
  254.         $70FA, $AAF2;
  255.  
  256.     { returns the statusRect of the module.  Very useful for drag-n-drop routines }
  257.     { because you no longer have to constantly set a global rectangle variable to }
  258.     { hold the current location of the module in the Strip window. }
  259.     {}
  260.         { Will not move memory. }
  261.     procedure SBGetModuleBounds (var bounds: Rect; moduleRefNum: ModuleReference);
  262.     inline
  263.         $70F9, $AAF2;
  264.  
  265. { Miscellaneous Utilities }
  266.  
  267.     { runs this (locked!) piece of code once within Extensions Strip's context.        }
  268.     { PPC modules must pass a valid routine descriptor to this function.  Since        }
  269.     { the descriptor will not be disposed of after the code has executed, I would    }
  270.     { recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule    }
  271.     { is called and disposing it upon sdevCloseModule.                                }
  272.     { A non-zero result code means that the UPP could not be queued (memory error).    }
  273.     {}
  274.         { May move memory! }
  275.     function SBQueueCode (theProc: SBQueueUPP; refCon: LONGINT): OSErr;
  276.     inline
  277.         $70F8, $AAF2;
  278.  
  279.     { sends the specified Apple Event within Extensions Strip's context to insure        }
  280.     { safe sending rather than trusting that the front application is AE aware.            }
  281.     { _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it        }
  282.     { must still be disposed of afterward by your code to free up memory (even            }
  283.     { though the event hasn't actually been sent yet.)                                    }
  284.     {}
  285.     { _SBSimpleAESend is meant to be an easy way to send simple events.  If you            }
  286.     { need to check the reply AppleEvent or the _AESend error, ect., you should queue    }
  287.     { your code (with _SBQueueCode or by having your module return 'sdevQueueModule')    }
  288.     { and send the Apple Event yourself.  The result returned by _SBSimpleAESend        }
  289.     { is only non-zero if an error occured while queueing the event for later sending.    }
  290.     {}
  291.     { Also, if an error does occur when Extensions Strip sends your AppleEvent, the        }
  292.     { user will be notified with a dialog that _AESend failed.                            }
  293.     {}
  294.     { Here are the parameters I give to _AESend.  They are basic enough for most        }
  295.     { kinds of Apple Events that modules send, hence the name _SBSimpleAESend.            }
  296.     { err := AESend(theAppleEvent, reply,                 your specified AppleEvent        }
  297.     {                                                    { and a dummy reply descriptor    }
  298.     {            kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer,     send mode        }
  299.     {            kAENormalPriority,                                     send priority    }
  300.     {            kAEDefaultTimeout,                                     time out            }
  301.     {            nil,                                                 idleProc            }
  302. {    {            nil);                                                 filterProc        }
  303. {    {}
  304.         { May move memory! }
  305.     function SBSimpleAESend ({CONST}
  306.                                     var theAppleEvent: longInt): OSErr;    {AppleEvent}
  307.     inline
  308.         $70F7, $AAF2;
  309.  
  310.  
  311.     { returns a pointer to the current event being processed.  Modififations to        }
  312.     { the data in this pointer WILL take effect as the event gets passed along        }
  313.     { to the other processes and jGNE filters further on in the chain.  Although    }
  314.     { a module can use this function at any time, it is really meant to be called    }
  315.     { within the sdevInterceptedEvent selector because this is where a module can    }
  316.     { deny other modules the proper processing of the event (such as in the case    }
  317.     { of a keyDown.)  Another good use for SBGetCurrentEvent() is to find the exact    }
  318.     { point where a mouseDown occured if you have a queue of clickable objects.        }
  319.     {}
  320.         { Will not move memory. }
  321.     type
  322.         EventRecordPtr = ^EventRecord;
  323.     function SBGetCurrentEvent: EventRecordPtr;
  324.     inline
  325.         $70F6, $AAF2;
  326.  
  327.     { For Extensions Strip 1.2 and later.                                    }
  328.     { Check for gestalt features bit 'gestaltHasSBResolveAliasFile'.        }
  329.  
  330.     { resolves a chain of alias files just like the toolbox routine ResolveAliasFile()    }
  331.     { but with an option to override the mounting of remote volumes.  Most of the code    }
  332.     { is from an Apple snippet in the Technote "Quietly Resolving Finder Aliases".        }
  333.     {}
  334.     { Also, in the event of the display of an AppleShare mounting dialog, if the            }
  335.     { current process is not in front, then the front process will be set to the            }
  336.     { current one.  Since Extensions Strip 1.2 and later can only be run as regular        }
  337.     { applications, the use of this trap is almost always safe to display mount            }
  338.     { dialogs.  You should, however, set the mounting of remote volumes to false        }
  339.     { if called inside a drop handler when the current process is not the front one.        }
  340.     {}
  341.         { May move memory! }
  342.     function SBResolveAliasFileMountOption (var fileFSSpec: FSSpec; resolveAliasChains: Boolean; var targetIsFolder: Boolean; var wasAliased: Boolean; mountRemoteVols: Boolean): OSErr;
  343.         $70F5, $AAF2;
  344.  
  345. implementation
  346. end.